Conversation
Signed-off-by: Phil Prasek <prasek@gmail.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📖 Docs PR preview links
|
Signed-off-by: Phil Prasek <prasek@gmail.com>
KeithB-Temporal
left a comment
KeithB-Temporal
left a comment
There was a problem hiding this comment.
This is a HUGE leap forward for Nexus documentation! Incredible work, Phil! I went through very thoroughly and added some comments to help support your great work and to make these changes even more awesome.
| [Temporal Nexus](/evaluate/nexus) allows you to reliably connect Temporal Applications. | ||
| It promotes a more modular architecture for sharing a subset of your team's capabilities with well-defined microservice contracts for other teams to use. | ||
| Nexus was designed with Durable Execution in mind and enables each team to have their own Namespace for improved modularity, security, debugging, and fault isolation. | ||
| :::info NEW TO NEXUS? |
There was a problem hiding this comment.
This was SUPER smart to change this page which is the first Google result for Temporal Nexus to being a guide that focuses on discovery rather than how to use. And I LOVE this callout that directs them to implementation stuff if they want to go there.
| The [Nexus Operation lifecycle](/nexus/operations#operation-lifecycle) supports both [synchronous](/nexus/operations#synchronous-operation-lifecycle) and [asynchronous](/nexus/operations#asynchronous-operation-lifecycle) Operations. | ||
| It is suitable for low-latency and long-running use cases. | ||
| Nexus Operations can be implemented with Temporal primitives, like Workflows, or [execute arbitrary code](/nexus/operations#executing-arbitrary-code-from-a-sync-handler). | ||
| - **Asynchronous** - Starts a Workflow (same or different Task Queue, with optional [Eager Start](/develop/worker-performance#eager-workflow-start)). Can run up to [60 days](/cloud/limits#nexus-operation-duration-limits). |
There was a problem hiding this comment.
Do we fully support Async today? I thought we needed Manual Completion work to complete this story...
There was a problem hiding this comment.
We do support async Nexus ops for starting a workflow today, using the SDK helper/builder New-Workflow-Run-Operation which is the primary thing Nexus handlers do today: start a workflow and return the result async.
We don't yet support custom async Nexus handlers where you might want to wrap an existing Kafka-based microservice with a Nexus service where the Nexus handler might publish a Kafka message to a topic, and then get an async response by consuming from a Kafka topic that would need manual Nexus op completion -- this is part of the outbound Nexus Connector work.
| - [Python SDK - Nexus quick start and code sample](/develop/python/nexus) | ||
| - [TypeScript SDK - Nexus quick start and code sample](/develop/typescript/nexus) | ||
| - [.NET SDK - Nexus quick start and code sample](/develop/dotnet/nexus) | ||
| :::tip SDK GUIDES |
There was a problem hiding this comment.
I love this, this is so much cleaner and takes up so much less space.
| See [system interactions](/nexus/operations/#system-interactions) for additional detail. | ||
| See [system interactions](/nexus/operations#system-interactions) for the full request flow. | ||
|
|
||
| ### Built-in Nexus Machinery |
There was a problem hiding this comment.
I think we should re-evaluate the use of Nexus Machinery as a term. It is jargony and it isn't really descriptive. Suggest something like Traffic Control or Durable Traffic Control
There was a problem hiding this comment.
It does a lot more than that, but let's discuss offline. Would keep this as-is for now as it's used in a lot of places.
|
|
||
| For example, when you execute a Nexus Operation in a caller Workflow, a command is sent to Temporal to schedule the Operation, and the Nexus Machinery is responsible for making the Nexus RPC calls on your behalf. | ||
| This means you don't have to use Nexus RPC directly, only the Temporal SDK along with the Temporal Service. | ||
| Nexus calls chain across teams and Namespaces: |
There was a problem hiding this comment.
This description line is a bit thin on explaination. I don't think it would be clear to a first time reader why they would would want to do this. I think an example use case here would help bring this home
There was a problem hiding this comment.
Good idea, feel free to add.
| See [Nexus Security in Temporal Cloud](/cloud/nexus/security) for more information. | ||
| See [Nexus security in Temporal Cloud](/cloud/nexus/security). | ||
|
|
||
| ## Terraform and Ops API support |
There was a problem hiding this comment.
I think this title should be "Automate Nexus Endpoint provisioning and lifecycle management" and the content should talk about using either Terraform or Ops API
| - [Errors in Activities](/references/failures#errors-in-activities) | ||
| - [Non-retryable errors](/references/failures#non-retryable) | ||
|
|
||
| This differs from Activity and Workflow error handling. |
There was a problem hiding this comment.
Good to know it is different. It might be good to add another sentence or two to describe the differences so the user doesn't need to grep 4 pages and compare and contrast the content.
|
|
||
| [Temporal Nexus](/nexus) allows you to reliably connect Temporal Applications. | ||
| It was designed with Durable Execution in mind and enables each team to have their own Namespace for improved modularity, security, debugging, and fault isolation. | ||
| [Temporal Nexus](/nexus) connects Temporal Applications across Namespaces with built-in durability, security, and fault isolation. |
There was a problem hiding this comment.
Do we even need this line for this page? This page is focused on self hosting, not learning Nexus. Recommend that we get rid of this line and the picture below and add a callout similar to the one we have on the main nexus page
NEW TO NEXUS?
This page explains how to Self-Host Nexus, To learn more about what Nexus is and how it works, see here (link to main Nexus page). To evaluate whether Nexus fits your use case, see the evaluation guide.
There was a problem hiding this comment.
adding a NEW TO NEXUS callout is a good idea 👍
| It was designed with Durable Execution in mind and enables each team to have their own Namespace for improved modularity, security, debugging, and fault isolation. | ||
| [Temporal Nexus](/nexus) connects Temporal Applications across Namespaces with built-in durability, security, and fault isolation. | ||
|
|
||
| <CaptionedImage |
There was a problem hiding this comment.
Recommend we remove this image and instead use call outs to send them to the learning and use cases pages to learn Nexus.
| Enable Nexus in your self-hosted Temporal Service by updating the server's static configuration file and enabling Nexus through dynamic config, then setting the public callback URL and allowed callback addresses. | ||
| Nexus is only supported in single cluster setups at this time. | ||
| For additional information on operating Nexus workloads in your self-hosted cluster, see [Nexus Architecture](https://github.com/temporalio/temporal/blob/main/docs/architecture/nexus.md). | ||
| Enable Nexus by updating your static configuration and dynamic config. |
There was a problem hiding this comment.
I think we are removed the dynamic config, right? @stephanos has a PR to remove this. See this Jira ticket: https://temporalio.atlassian.net/browse/NEXUS-231
| - **Multi-region connectivity** - Nexus requests route across Namespaces within and across AWS and GCP using a global mTLS-secured Envoy mesh. Compatible with [Multi-region Namespaces](/cloud/high-availability#multi-region-replication) as Endpoint targets. | ||
| - **[Terraform support](/cloud/terraform-provider#manage-temporal-cloud-nexus-endpoints-with-terraform)** - Manage Nexus Endpoints with the Temporal Cloud Terraform provider. | ||
|
|
||
| <CaptionedImage |
There was a problem hiding this comment.
This is great!! I wonder if this image is a bit overwhelming for this page. We could workshop other overview diagrams or replace it with a simpler one. Not a blocking comment though.
bergundy
left a comment
bergundy
left a comment
There was a problem hiding this comment.
I didn't quite get to finish the review but since this has been open for a while now, I figured I would submit what I have so far.
| Communication across different regions will have higher latency. | ||
| Consult the cross-region latency tables for your cloud provider(s) to estimate the latency for Nexus communication across Namespaces in Temporal Cloud. | ||
| - **SLOs and SLAs** - Nexus requests have the same [latency SLOs](/cloud/service-availability#latency) and [availability SLAs](/cloud/sla) as other Worker requests in both caller and handler Namespaces. | ||
| - **[Nexus metrics](/nexus/metrics)** - SDK and Cloud latency metrics for monitoring Nexus performance. |
There was a problem hiding this comment.
I don't think we expose any cloud metrics for Nexus yet?
| - [Per-Workflow Nexus Operation limits](/cloud/limits#per-workflow-nexus-operation-limits) - 30 in-flight Operations per Workflow. | ||
| - [Nexus Operation request timeout](/cloud/limits#nexus-operation-request-timeout) - Less than 10 seconds for a handler to process a start or cancel request. | ||
| - [Nexus Operation duration limits](/cloud/limits#nexus-operation-duration-limits) - 60-day maximum ScheduleToClose duration. | ||
| - [Per-Workflow callback limits](/cloud/limits#per-workflow-callback-limits) - Governs how many Nexus callers can attach to a handler Workflow. |
There was a problem hiding this comment.
Put the new limit here (2000)?
| ``` | ||
| temporal operator namespace create --namespace my-target-namespace | ||
| temporal operator namespace create --namespace my-caller-namespace | ||
| temporal operator namespace create --namespace nexus-simple-handler-namespace |
There was a problem hiding this comment.
Is this taken from the .NET sample? Why did it change?
|
|
||
| ```csharp | ||
| [NexusOperationHandler] | ||
| public IOperationHandler<SignalInput, SignalOutput> SignalWorkflow() => |
There was a problem hiding this comment.
Can you confirm that this compiles?
|
|
||
| A common pattern is to use the Temporal Client from within a sync handler to Signal, Query, or Update a Workflow. | ||
| You can also use Signal-With-Start or Update-With-Start to ensure the Workflow is started and send it a Signal or Update. | ||
| All calls must complete within the [Nexus request timeout](/cloud/limits#nexus-operation-request-timeout). Updates should be short-lived to stay within this deadline. |
There was a problem hiding this comment.
Maybe put a blurb about how the provided context is set with this deadline?
| By default, Nexus handler errors are considered retryable, unless specified below: | ||
| By default, handler errors are retryable unless they are: | ||
|
|
||
| - [Application Failures](/references/failures#nexus-errors) marked as non-retryable. |
There was a problem hiding this comment.
| - [Application Failures](/references/failures#nexus-errors) marked as non-retryable. | |
| - [Application Failures](/references/failures#nexus-errors) explicitly marked as non-retryable. |
|
|
||
| - [Application Failures](/references/failures#nexus-errors) marked as non-retryable. | ||
| - [Unsuccessful Operation errors](/references/failures#nexus-errors) that can resolve an operation as either failed or canceled. | ||
| - [Unsuccessful Operation errors](/references/failures#nexus-errors) that resolve an Operation as failed or canceled. |
There was a problem hiding this comment.
| - [Unsuccessful Operation errors](/references/failures#nexus-errors) that resolve an Operation as failed or canceled. | |
| - [Nexus Operation errors](/references/failures#nexus-errors) that resolve an Operation as failed or canceled. |
| Nexus Operation token. | ||
| The reason for the failure is in the message and in the underlying cause is typically an Application Error or a Canceled Error. | ||
| When a Nexus Operation fails, the caller receives a Nexus Operation Failure containing the Operation name, token, and failure reason. | ||
| The underlying cause is typically an Application Error or Canceled Error. |
| Enable tracing by installing an interceptor on the Client or Worker: | ||
|
|
||
| - [Go SDK](https://github.com/temporalio/samples-go/tree/main/opentelemetry) | ||
| - [Java SDK](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/tracing) |
There was a problem hiding this comment.
Need to add Python and other SDKs here, are we tracking this?
There was a problem hiding this comment.
Are we concerned about broken links here?
5 participants
What does this PR do?
Nexus docs update:
┆Attachments: EDU-5974 Nexus docs update